KMC - Using and Extending the KMC Platform - Collaboration

Overview

Collaboration rooms are part of SAP Enterprise Portal. The portal includes standard iViews for common tasks such as room creation and administration. Existing rooms are listed in the Room Directory iView. You can also enter rooms from there in order to collaborate with other users in the same room, again using standard iViews. However, if you want to carry out advanced or specialized tasks in rooms, there is a Collaboration Rooms API that you can access from any portal application, iView, or room extension.

This document is designed to help developers to become familiarized with the Collaboration Room 6.0 API. It helps you to understand the public parts of the Collaboration Room programming environment and to carry out initial steps using the API.

The first part of this document is dedicated to the technical structure of the Collaboration Room 6.0 framework and its integration into SAP Enterprise Portal and KM. The second part consists of practical information and examples of how to use the Collaboration Rooms API.

Architecture

The Collaboration Room 6.0 framework combines different functional aspects of both the portal and the KM platform into one consistent solution. The Rooms API provides an abstraction from this heterogeneous system landscape and therefore offers scenario-oriented access to the functionality of the rooms. Three main parts of SAP Enterprise Portal and KM framework are used to store rooms and room-related information:

PCD
User Management
Repository Framework

The PCD is used to store the portal-related parts of existing room instances such as worksets, pages, and iViews. It is also used as a store for the room templates that make the room creation process much easier for end users.

User management is used to store user-to-room and user-to-room role assignments.

The repository framework is used to create a semantic object for each room. These room objects hold all room information that is not stored in one of the other two layers. This includes the name and description of the room, and other basic information.

Graphic 1: Architecture

The following steps are performed by the Collaboration Room framework when a new room is created:

An application calls the Rooms API method createRoom() and passes all relevant data for the new room as a parameter.
The Collaboration Room backend calls the User Management API to
- Create a user group containing all users of the new room
- Create a user group for each room role containing the users assigned to the role in question
For compatibility reasons to older versions of the Collaboration Room framework, the Repository Framework API is called to
- Create a public and a private folder for each selected content store (in the template)
- Copy content from the content template folders to the new private folders
- Create a Public Area folder containing links to all new public folders
- Create a Structure folder containing links to all new private folders and another link to the Public Area folder
- Set appropriate ACL permissions for all these new folders in the structure
The Repository Framework API is called to
- Create a new folder resource in a special repository that represents the room itself
- Set the name, description, and so on of the room as properties of the new room resource
- Create a link from the room resource to the room Structure folder
- Set ACL permissions for the room resource
The Portal Connector API is called to
- Copy the template workset (including pages and iViews) into a special PCD folder
- Map all room parameters (including the hidden parameters such as room ID and so on) to the iView parameters according to the mapping rules defined in the template
The Groupware API is called to send invitation e-mails to all users of the new room
The Status Engine API is called to create a status event for the room creation
At each extension point during the room creation process, the Extension framework calls the extensions defined in the template to enable the connection of other backend systems and to add additional functionality to the new room

For more information on the Extension framework and how to write new extensions, see the Room Extension Developer Guide.

Rooms API Functionality

Here is a list of the features provided by the Rooms 6.0 API grouped by functionality.

Actions

Create new rooms
Check for existence of rooms
Retrieve existing rooms by ID
Retrieve rooms for a given user
Retrieve rooms with a given privacy
Retrieve most/least visited rooms
Create or delete typed relations between rooms
Search for typed relations between rooms
Delete rooms

Room-Instance-Based Information Functionality

Room name
Room description
Creation date of the room
Version of the room object
Date of the last modification of the room
Date when the room was last entered by a given user
Date when the room was last entered by any user
Internal/external room access URL
Unique ID of the room
Internal/external room parameters
Room categories
Template name
Template description
Room privacy
Lock state
Hidden state
Room owner
Room users
Room roles
Members of a given room role
Room roles of a given user
Check whether a user is room member
Check whether a room has public content
Usage information for the room
Room events
Room parts
Position of room parts in the Detailed Navigation iView

Modifications of a Room instance

Room name can be changed
Room description can be changed
Room owner can be changed
Room privacy type can be changed
Room categories can be changed
Room parameters can be changed
Application properties can be set at the room instance
Hide/unhide room
Lock/unlock room
Invite new members to a room
Remove users from a room
Change a user's roles in a room
Add a user to a room role
Remove a user from room roles
Register/deregister a user in a community
Add/remove room parts
Change the order of room parts in the Detailed Navigation iView

Rooms API Structure

The technical structure of the Collaboration Rooms 6.0 API is realized through several Java interfaces. It consists of five main parts (interfaces), which are listed below.

Rooms API

The Rooms API is the entry point for other applications to access the functionality provided by the Collaboration Room framework.

The Rooms API is accessible as a KM service and as a portal service in the portal environment. It does not work on an instance level, but on a factory level that provides access to specific room instances.

RoomObject API

The RoomObject API provides access to the functionality of a specific room instance. For example, an application might use the RoomObject API to invite new users to an existing room.

The RoomObject API is implemented directly by RoomObjects. RoomObjects are implemented as semantic objects in the repository framework.

RoomInfo API

The RoomInfo API is implemented by the RoomInfo object. The RoomInfo object handles parts of the instance data of a RoomObject. It is similar to a partial snapshot of a related RoomObject and can be used to create new rooms. The RoomInfo API therefore provides mandatory field validation and consistency checks for the contained data. The RoomInfo object is also passed to room extensions in order to provide them with information about the room in question.

RoomInfo objects do not contain the following information:

Portal-related information (worksets, pages, and so on)
Room content (documents, business objects, and so on)

RoomUsers API

The RoomUsers API provides access to the user-related functionality of a room instance, such as changing the user-role assignments. The RoomUsers API is implemented by a RoomUsers object that contains the user-role assignments for a specific room.

There are several reasons why the user-related functionality has been separated from the RoomObject API into a separate API:

To keep these rarely used methods together, but separated from the RoomObject API methods
Changes to the RoomUsers object do not affect the corresponding room immediately. An application might carry out several changes to the same RoomUsers object (for example, invite new users, cancel the invitation for certain users, and change the roles of other users) and then apply the changes in one step to the room itself. Like in a transactional environment, this prevents the room from having inconsistent or non-final states at certain points in time.

The RoomUsers API is coupled with the Status Engine. All changes to the user-role assignments of a room are tracked by the Status Engine using Status Events.

The RoomUsers API is also coupled with the e-mail messaging features of the Collaboration framework. For example, when a new user is assigned to a room, an invitation e-mail is sent to the user in question.

An instance of the RoomUsers interface is also passed to room extensions at certain extension points in order to provide a set of affected user-role assignments to the extension (for example, added room users or removed room users).

Room Relations API

The Room Relations API is implemented by the room relation manager, which can be obtained from the Rooms API. It provides methods for creating or deleting relations between rooms. Each relation has a specific relation type and relates a source room with a target room.

The Relations API also provides methods for searching existing relations by

Source room
Source room and relation type
Target room
Target room and relation type

There is no semantic connection between two related rooms. For instance, there is no role inheritance or content sharing between related rooms. Also, the members of the source room can be completely different from those of the target room. A relation is only a link between one room and another room that makes navigation between the two rooms easier. The Related Rooms iView displays links to all related target rooms and the Related Rooms Admin iView provides a user interface for maintaining these links.

Room Status Event API

The Room Status Event API provides access to the room-related status events that are automatically logged during system operation.

The following functionality is provided:

Retrieval of status events related to a certain room
Retrieval of room usage data

The status events that are related to a certain room can be retrieved using the RoomObject API (access to the events of the respective room) or the Rooms API (the room has to be specified by its ID). It is possible to filter the events by time stamp, by the status action (defined in RoomStatusAction), and by the user who caused the events.

The room usage data can be accessed in two ways: Usage data related to a specific room can be accessed using the RoomObject API and the Rooms API; data regarding the most visited or least visited rooms is accessible using the Rooms API only.

Prerequisites

Compile Time

In order to be able to use the Rooms API in your code and to compile it, you have to include the following jar file in your project:

coll.shared.roomobject_api.jar

This file can be found in an installed NW '04 or 6.0 SP2 CP portal at the following location:

...\WEB-INF\portal\portalapps\com.sap.netweaver.coll.shared\lib

The way in which this is done depends on your programming environment. In an Eclipse project environment, for example, you can add the jar file under:

Project ->Properties ->Java Build Path ->Libraries

Runtime

The runtime environment for the Collaboration Rooms API is an NW '04 or a 6.0 SP2 CP installation. Before deploying your new application code (accessing the Rooms API), you have to add a new Service Reference to your portalapp.xml file:

...

<application-config>

   ...

   <property name="ServicesReference"
         value="...,com.sap.netweaver.coll.shared,..."/>

   ...

</application-config>

...

Usage Cases for the Rooms 6.0 API

To keep these examples useful and simple, no error handling is carried out in the code. Exceptions are just passed to the calling methods.

For more information on specific method calls or parameters in the method's signatures, see the Java Documentation for the interfaces.

How to... Get access to the rooms KM service/portal service

As mentioned before, the Collaboration Rooms 6.0 API is available as a KM service and as a portal service. To get access to the API, you have to include the correct import statement and instantiate one of the services:

import com.sap.ip.collaboration.room.api.IRooms;
import com.sapportals.wcm.service.ServiceFactory;

IRooms roomsAPI = (IRooms)
       ServiceFactory
       .getInstance()
       .getService(IRooms.KM_SERVICE_ID);

import com.sap.ip.collaboration.room.api.IRooms;
import com.sapportals.portal.prt.runtime.PortalRuntime;

IRooms roomsAPI = (IRooms)
       PortalRuntime
       .getRuntimeResources()
       .getService(IRooms.PORTAL_SERVICE_ID);

How to... retrieve all rooms to which a user belongs

You can use the rooms service to get a list of rooms to which a given user belongs.

API methods:

IRoom[] IRooms.getAllRoomsForUser(com.sap.security.api.IUser user)

Returns all rooms to which the given userbelongs.

//imports for Collaboration Rooms
import com.sap.ip.collaboration.room.api.IRoom;
import com.sap.ip.collaboration.room.api.IRooms;

//imports for Portal
import com.sapportals.portal.prt.runtime.PortalRuntime;

//imports for User Management
import com.sap.security.api.IUser;
import com.sap.security.api.UMFactory;
import com.sap.security.api.UMException;

public void retrieveJohnsRooms() throws UMException
{
  //Get the Rooms API Service
  IRooms roomsAPI = (IRooms)
       PortalRuntime
       .getRuntimeResources()
       .getService(IRooms.PORTAL_SERVICE_ID);

  //Get a user from User Management
  IUser john = UMFactory.getUserFactory().getUserByLogonID("SmithJ");

  //Retrieve John's Rooms
  IRoom[] johnsRooms = roomsAPI.getAllRoomsForUser(john);

  //Iterate over John's Rooms
  for(int i = 0; i < johnsRooms.length; i++)
  {
    String roomName = johnsRooms[i].getName();
    //...
  }
}

How to… create a new room

Creating new collaboration rooms using the Rooms API consists of several steps. In this example, a very simple room is created. Most attributes of the new room are filled with default values from the room template.

Graphic 2: Room Creation Process

The application needs an empty RoomInfo object in order to create a new room. This is obtained by calling the Rooms API method getRoomCreationInfo().
An empty RoomInfo object is returned by the Rooms API. This object implements the interface IRoomInfo but contains no data as yet.
The application calls setName(), setDescription() and other set...() methods directly at this RoomInfo object instance to set the required data. It's up to the application to call more or fewer set...() methods in this step in order to have control over more or less detail in the new room. Some calls to set...() methods can be skipped. In this case, default values are taken from the room template, which has to be set by calling setTemplateName().
When all desired data has been set, the application calls validate() at the RoomInfo object instance. This method checks for missing or inconsistent data in the RoomInfo object. If this call returnstrue, everything is ok. If it returns false, a further call to getValidationErrors() provides more information about the error.
The application calls createRoom() and passes the RoomInfo object as a parameter to the Rooms API.
If room creation in the rooms backend was successful, an instance of IRoom is returned. This instance represents the new room. If there were any errors during the room creation process, a RoomCreationException is thrown. The exception contains more information about the error itself, or the causing exception as a nested exception.
The application uses the returned instance of IRoom for further tasks (RoomObject API).

API methods:

ITemplate IRooms.getRoomTemplate(String templateName)

Returns the room template named templateName.

IRoomRole ITemplate.getRoomRole(String roleName)

Returns the room role named roleName from a template instance.

IRoomInfo IRooms.getRoomCreationInfo()

Returns an empty instance of IRoomInfo, which is needed for room creation.

boolean IRoomInfo.setName(String newName)

Sets the name of the new room to newName

boolean IRoomInfo.addRoomParameter(String paramName, String paramDesc, String paramValue, boolean isHidden)

Adds a parameter to the new room. This parameter is mapped like all others to the iViews of the room according to the mapping rules stored in the template. Parameter isHidden should normally be false.

boolean IRoomInfo.setOwnerId(String newOwnerId)

Sets the owner of the new room. newOwnerId is the unique ID of the user who is to become the room owner.

boolean IRoomInfo.addUserToRole(String userId, IRoomRole userRole)

Assigns the user userId to the room role userRole.

boolean IRoomInfo.validate()

Performs checks on the RoomInfo object. All required fields need to have a value, and data must be consistent. The method returns trueif everything is okay for room creation. If false, a call to IRoomInfo.getValidationErrors() provides more information about the error(s).

IRoom IRooms.createRoom(IRoomInfo info, boolean sendNotifications)

Creates a new collaboration room using all the values set in the IRoomInfo instance passed as the parameter info. Before the new room is created, info.validate() is called to make sure that the data is okay. If sendNotifications is true, e-mail notifications are sent out to the new room users. If the room creation is successful, a new instance of IRoom is returned to the caller. If errors occur, a RoomCreationException (nested exception) is thrown containing more information about the error.

public void createRoom() throws TemplateNotFoundException, NoSuchRoleException,
      UMException, RoomCreationException
{
  String templateName = "Template1";
  String roleName = "Role1";

  //Get the Rooms 6.0 API Portal Service
  IRooms roomsAPI = (IRooms)
  PortalRuntime.getRuntimeResources().getService(IRooms.PORTAL_SERVICE_ID);

  //Get Template Related Infos
  ITemplate template = roomsAPI.getRoomTemplate(templateName);
  IRoomRole role1 = template.getRoomRole(roleName);

  //Get an empty RoomInfo object
  IRoomInfo roomInfo = roomsAPI.getRoomCreationInfo();

  //Fill RoomInfo object with values
  roomInfo.setName("New Room Name");
  roomInfo.setDescription("New Room Description");
  roomInfo.setTemplateName(templateName);
  roomInfo.addRoomParameter("ParamName", "ParamDesc", "ParamValue", false);

  //Set User Role Assignments
  IUser owner = UMFactory.getUserFactory().getUserByLogonID("SmithJ");
  roomInfo.setOwnerId(owner.getUniqueID());
  roomInfo.addUserToRole(owner.getUniqueID(), role1);

  //Finally Create the Room
  if(roomInfo.validate())
    roomsAPI.createRoom(roomInfo, true);
}

How to… change an existing room

In this example, an application holds the ID of an existing room and wants to invite a new member into the room and change the roles of some of the existing room members.

Graphic 3: Change Room Users

The application calls the Rooms API method getRoom() and passes the room ID of the room as a parameter.
If a room with the given ID exists, the Rooms API returns an instance of that room.
The application calls the Rooms API method getRoomUsers() directly at the room instance.
An instance of IRoomUsers, which holds the current user-room role assignments, is returned.
The application uses the RoomUsers API to modify user-room role assignments. For instance, it calls addUserRole() to invite a new user to the room.
When all the changes to the RoomUsers object have been carried out, the application calls setRoomUsers() at the room instance and passes the RoomUsers object as a parameter. This call applies all changes to the room itself. The second parameter of this call (boolean) tells the Rooms framework whether the messaging features should be used (for example, if invitation e-mails should be sent out to new users).

API methods:

IRoom IRooms.getRoom(String roomId)

Returns an instance of the room with the ID roomId.

IRoomUsers IRoom.getRoomUsers()

Returns an instance of IRoomUsers containing all user-room role assignments for the room.

IUserRoles IRoomUsers.addUserRole(String userId, IRoomRole userRole)

Adds the user userId to the room role userRole. This assignment is carried in the RoomUsers instance - the room itself is not affected. It returns the UserRoles object for the given user, containing contains all room roles that are assigned to the user in question.

String[] IRoomUsers.getAllUsers()

Returns an array with all the user IDs of the room members.

IRoomRole[] IRoomUsers.getUserRoles(String userId)

Returns an array containing all room roles that are assigned to a given user.

boolean IRoom.setRoomUsers(IRoomUsers roomUsers, boolean sendNotifications)

Applies all changes carried out in the RoomUsers object roomUsers to the room itself. If sendNotifications is set to true, e-mail notifications are sent to affected users.

public void changeUserRoles() throws RoomInstantiationException, UMException
{
  //Get the Rooms 6.0 API Portal Service
  IRooms roomsAPI = (IRooms)
  PortalRuntime.getRuntimeResources().getService(IRooms.PORTAL_SERVICE_ID);

  //Get a Room
  IRoom room = roomsAPI.getRoom("4711");

  //Get the initial role of the room
  IRoomRole newRole = room.getInitialRoomRole();

  //Get the Room Users
  IRoomUsers roomUsers = room.getRoomUsers();
  IUser newUser = UMFactory.getUserFactory().getUserByLogonID("SmithJ");
  roomUsers.addUserRole(newUser.getUniqueID(), newRole);
  String[] userIds = roomUsers.getAllUsers();

  //iterate over all room users
  for(int i=0; i<userIds.length; i++)
  {
    IRoomRole[] userRoles = roomUsers.getUserRoles(userIds[i]);
    //... do something with the user's roles
  }

  //Apply all changes to the Room and send no notification emails
  room.setRoomUsers(roomUsers, false);
}

How to... create a room part

In this version of the API, a new room part can only be created in an existing room. Room part instances cannot be moved to or shared with other rooms, and it is not possible to create room parts outside of rooms.

This means that you need to get an instance of a room first, and then use the RoomObject API to create a new room part within that room.

In this example, you need not only the rooms service to get a room instance, but also the RoomParts Service which provides access to the RoomPartTemplate Service. You can use this service to instantiate a room part template.

API methods:

IRoomPartTemplate IRoomPartTemplateService.getRoomPartTemplate(String roomPartTemplateId) throws NoSuchRoomPartTemplateException

Returns the room part template named roomPartTemplateId.

IRoomRole[] IRoomPartTemplate.getRoomPartRoles()

Returns all roles defined in this room part template.

IRoleMapping RoomPartDataFactory.createRoleMapping(IRoomRole roomRole, IRoomRole roompartRole);

This method creates a mapping object for mapping a room part role to a room role.

IParameterMapping RoomPartDataFactory.createParameterMapping(String roomPartParameterName, String roomParameterName)

This method creates a mapping object for mapping a room part parameter to a room parameter.

IRoomParameterValue TemplateDataFactory.createRoomParameterValue(String parameterName, String description, String parameterValue, boolean hidden)

Creates an IParameterValue object with the given properties parameterName, description, parameterValue. The last parameter hidden should always be false for room part parameters.

IRoomPart createRoomPartInstance(String name, String roomPartTemplate, IRoleMapping[] roleMappings, IRoomParameterValue[] parameters, IParameterMapping[] parameterMappings) throws RoomPartCreationException

This method creates a new instance of IRoomPart with the given name, based on the given roomPartTemplate.

The mappings for room part roles to room roles need to be passed in the array parameterMappings.

The array parameters should contain all external parameters of the room part template with their corresponding values, whereas parameterMappings is used to pass all parameters of the room part template that are mapped to room parameters.

An instance of IRoomPart is returned if the creation is successful. If not, a RoomPartCreationException is thrown.

int IRoom.setPosition(String roomPartId, int newPosition) throws RoomException

You can use this method of the RoomObject API to change the position of any room part in the Detailed Navigation iView. The parameter newPosition can be set to any value greater or equal to 0. There are predefined values for the top and bottom position: IRoom.DTN_ITEM_POS_TOP andIRoom.DTN_ITEM_POS_BOTTOM. The return value is the new position of the room part after the call.

import com.sap.ip.collaboration.room.api.IRoom;
import com.sap.ip.collaboration.room.api.IRooms;
import com.sap.ip.collaboration.room.api.Exceptions.RoomException;
import com.sap.ip.collaboration.room.api.Exceptions.RoomInstantiationException;
import com.sap.ip.collaboration.room.api.roomparts.IParameterMapping;
import com.sap.ip.collaboration.room.api.roomparts.IRoleMapping;
import com.sap.ip.collaboration.room.api.roomparts.data.RoleMapping;
import com.sap.ip.collaboration.room.api.roomparts.data.RoomPartDataFactory;
import com.sap.ip.collaboration.room.api.template.IRoomParameter;
import com.sap.ip.collaboration.room.api.template.IRoomParameterValue;
import com.sap.ip.collaboration.room.api.template.IRoomRole;
import com.sap.ip.collaboration.room.api.template.data.TemplateDataFactory;
import com.sap.netweaver.coll.room.api.roomparts.IRoomPart;
import com.sap.netweaver.coll.room.api.roomparts.IRoomPartsService;
import com.sap.netweaver.coll.room.api.roomparts.exceptions
       .NoSuchRoomPartTemplateException;
import com.sap.netweaver.coll.room.api.roomparts.exceptions
       .RoomPartCreationException;
import com.sap.netweaver.coll.room.api.roomparts.template.IRoomPartTemplate;
import com.sap.netweaver.coll.room.api.roomparts.template.IRoomPartTemplateService;
import com.sapportals.portal.prt.runtime.PortalRuntime;

public void createRoomPart() throws RoomPartCreationException,
                                    RoomInstantiationException,
                                    NoSuchRoomPartTemplateException,
                                    RoomException
{
  String rpTemplateName = "Demo RoomPart";

  //Get the RoomParts Service
  IRoomPartsService rpService = (IRoomPartsService)
                                PortalRuntime.getRuntimeResources()
                                .getService(IRoomPartsService.PORTAL_SERVICE_ID);

  //Get the RoomPartTemplate Service
  IRoomPartTemplateService rpTemplateService =
                           rpService.getRoomPartTemplateService();

  //Get the Rooms 6.0 API Portal Service
  IRooms roomsAPI = (IRooms)
                     PortalRuntime.getRuntimeResources()
                    .getService(IRooms.PORTAL_SERVICE_ID);

  //Get a room
  IRoom room = roomsAPI.getRoom("4711");

  //Get the RoomPart template
  IRoomPartTemplate rpTemplate = 
                    rpTemplateService.getRoomPartTemplate(rpTemplateName);

  //Get the Room roles
  IRoomRole[] rRoles = room.getAllRoomRoles();

  //Get the RoomPart roles
  IRoomRole[] rpRoles = rpTemplate.getRoomPartRoles();

  //Create an array for all role mappings
  IRoleMapping[] roleMappings = new IRoleMapping[rpRoles.length];
  for(int i=0; i<rpRoles.length; i++)
  {
    //Map the RoomPart roles somehow to the room roles
    roleMappings[i] = RoomPartDataFactory.createRoleMapping(rRoles[i], rpRoles[i]);
  }

  //Get the RoomPart parameters
  IRoomParameter rpParameters[] = rpTemplate.getRoomPartParameters();

  //Create a parameter mapping for the first RoomPart parameter
  IParameterMapping[] rpParamMappings = new IParameterMapping[1];
  rpParamMappings[0] = RoomPartDataFactory.createParameterMapping
                       (
                         rpParameters[0].getParameterName(), 
                         "Room Parameter 1"
                       );

  //Create an array for all other RoomPart parameters and assign values
  IRoomParameterValue[] rpParamValues = new
                                        IRoomParameterValue[rpParameters.length-1];
  for(int i=1; i<rpParameters.length; i++)
  {
    //Create some values for the RoomPart parameters
    rpParamValues[i] = TemplateDataFactory.createRoomParameterValue
                       (
                         rpParameters[i].getParameterName(), 
                         rpParameters[i].getDescription(), 
                         "Parameter Value " + i, 
                         false
                       ); 
  }

  //Finally create the new RoomPart
  IRoomPart roomPart = room.createRoomPartInstance
                       (
                         "RoomPart Name", 
                         rpTemplateName, 
                         roleMappings, 
                         rpParamValues, 
                         rpParamMappings
                       );

  //Move the new RoomPart to the TOP of the Detailed Navigation List
  room.setPosition(roomPart.getId(), IRoom.DTN_ITEM_POS_TOP);
}

How to... create a room relation

You can now use the Room Relations API to create relations between rooms. The API is implemented by the relation manager, which can be obtained by the Rooms API. It provides methods for creating new relations, searching for existing ones, and deleting them.

Each relation is characterized by a source room, a target room, and a relation type. A list of possible relation types is maintained in the configuration of the portal. These relation types can also be accessed using the RelationManager API.

API methods:

IRelationManager IRooms.getRelationManager()

This method returns an instance of the relation manager

List IRelationManager.getAllAssociationIds()

The List returned by this method contains the IDs (as Strings) of all relation types configured in the system. A localized name of the relation type can be obtained by calling the method IRelationManager.getAssociationLabel(String associationId, Locale locale).

void relateRoom(String sourceRoomId, String targetRoomId, String associationId) throws ResourceException

This method creates a new relation between the room sourceRoomId and the room targetRoomId with the relation type associationId.

List getRelatedRoomsFromRoom(String sourceRoomId, String associationId) throws ResourceException

This method searches for all target rooms of a given source room with a given relation type. There is also a signature of this method without associationId, so really all target rooms with all relation types can be found.

It is also possible to search for all source rooms of a given target room. This is done by the methods IRelationManager.getRelatedRoomsToRoom(String targetRoomId) and IRelationManager.getRelatedRoomsToRoom(String targetRoomId, String associationId).

void unrelateRoom(String sourceRoomId, String targetRoomId, String associationId) throws ResourceException

This method deletes one specific room relation.

It is also possible to delete all relations where a specific room is source or target room in one call: IRelationManager.deleteRoomRelations(String sourceRoomId).

import java.util.List;
import com.sap.ip.collaboration.room.api.IRooms;
import com.sap.ip.collaboration.room.api.relman.IRelationManager;
import com.sapportals.portal.prt.runtime.PortalRuntime;
import com.sapportals.wcm.repository.ResourceException;

public void relateRooms() throws ResourceException
{
  String sourceRoomId = "4711";
  String targetRoomId = "4712";

  //Get the Rooms 6.0 API Portal Service
  IRooms roomsAPI = (IRooms)
                    PortalRuntime.getRuntimeResources()
                    .getService(IRooms.PORTAL_SERVICE_ID);

  //Get the RelationManager
  IRelationManager relMan = roomsAPI.getRelationManager();

  //Retrieve a list of possible relation types
  List types = relMan.getAllAssociationIds();

  //Relate two rooms with the first available relation type
  relMan.relateRoom(sourceRoomId, targetRoomId, (String) types.get(0));

  //Search for target rooms of room "4711"
  List targetRooms = relMan.getRelatedRoomsFromRoom(sourceRoomId, 
                                                    (String) types.get(0));

  String roomId = (String) targetRooms.get(0); //roomId should be "4712" now

  //Delete relation
  relMan.unrelateRoom(sourceRoomId, targetRoomId, (String) types.get(0));
}

How to… get the most used rooms

This example shows how the Room Status API is used to find the most visited rooms for the last week.

API methods:

IRoomUsage[] IRooms.getMostVisitedRooms(int listLength, long timeStamp)

Returns an array containing the usage data for the most visited rooms.

//imports for Collaboration Rooms
import com.sap.ip.collaboration.room.api.IRoom;
import com.sap.ip.collaboration.room.api.IRooms;
import com.sap.ip.collaboration.room.api.IRoomUsage;

//imports for Portal
import com.sapportals.portal.prt.runtime.PortalRuntime;

// misc
import java.util.Date;
import java.util.GregorianCalendar;

public void printMostVisitedRooms() throws RoomInstantiationException
{
  //Get the Rooms API Service
  IRooms roomsAPI = (IRooms)
       PortalRuntime
       .getRuntimeResources()
       .getService(IRooms.PORTAL_SERVICE_ID);

  // get time stamp for one week ago
  GregorianCalendar calendar = new GregorianCalendar();
  calendar.add( GregorianCalendar.WEEK_OF_YEAR, -1 );
  long timeStamp = calendar.getTime().getTime();

  // get the ten most visited rooms for the last week
  IRoomUsage[] roomUsageData = roomsAPI.getMostVisitedRooms( 10, timeStamp );

  // print the room name and the number of visits
  System.out.println("Top ten rooms for the last week:");
  for ( int i = 0; i < roomUsageData.length; i++ )
  {
    System.out.print("Room name: ");
    System.out.print(roomsAPI.getRoom(roomUsageData[i].getRoomId()).getName());
    System.out.println(", number of visits: " + roomUsageData[i].getVisits() );
  }
}

How to… find unused rooms

This is an example of how the Room Status API can be used to find rooms that have not been used for a certain amount of time (for instance to delete or archive them).

API methods:

IRoomUsage[] IRooms.getLeastVisitedRooms(int listLength, long timeStamp)

Returns an array containing the usage data for the least visited rooms.

//imports for Collaboration Rooms
import com.sap.ip.collaboration.room.api.IRoom;
import com.sap.ip.collaboration.room.api.IRooms;
import com.sap.ip.collaboration.room.api.IRoomUsage;

//imports for Portal
import com.sapportals.portal.prt.runtime.PortalRuntime;

// misc
import java.util.Date;
import java.util.GregorianCalendar;

public void printUnusedRooms() throws RoomInstantiationException
{
  //Get the Rooms API Service
  IRooms roomsAPI = (IRooms)
       PortalRuntime
       .getRuntimeResources()
       .getService(IRooms.PORTAL_SERVICE_ID);

  // get time stamp for one month ago
  GregorianCalendar calendar = new GregorianCalendar();
  calendar.add( GregorianCalendar.MONTH, -1 );
  long timeStamp = calendar.getTime().getTime();

  // get the 25 least visited rooms for the last week
  IRoomUsage[] roomUsageData = roomsAPI.getLeastVisitedRooms( 25, timeStamp );

  // print the room name
  System.out.println("Rooms which are not used for at least a month:");
  // the result is ordered ascending, so the unused rooms come first
  int i = 0;
  while ( (i < roomUsageData.length ) && ( roomUsageData[i].getVisits() == 0 ) )
  {
    System.out.println(
      roomsAPI.getRoom( roomUsageData[i].getRoomId() ).getName() );
    i++;
  }
  System.out.println("Number of unused rooms: " + i );
  // in case all 25 rooms are unused we might have to check again with a higher
  // number to get all unused rooms !!
}

How to… retrieve all room user changes for a room

This example shows you how to find all status events that are related to room user changes (adding a user to a room, removing a user from a room, and changing the role of a room user) for a certain room.

API methods:

IRoomStatusEvent[] IRoom.getRoomEvents( long timestamp, RoomStatusAction[] roomActions, String[] userIds, int maxResultSize )

Returns an array containing the retrieved status events.

//imports for Collaboration Rooms
import com.sap.ip.collaboration.room.api.IRoom;
import com.sap.ip.collaboration.room.api.IRooms;
import com.sap.ip.collaboration.room.api.IRoomStatusEvent;
import com.sap.ip.collaboration.room.api.RoomStatusAction;

//imports for Portal
import com.sapportals.portal.prt.runtime.PortalRuntime;

public void retrieveUserChangeEvents() throws RoomInstantiationException
{
  //Get the Rooms API Service
  IRooms roomsAPI = (IRooms)
       PortalRuntime
       .getRuntimeResources()
       .getService(IRooms.PORTAL_SERVICE_ID);

  //Get a room
  IRoom room = roomsAPI.getRoom("4711");

  // get all user related status events for the room
  IRoomStatusEvent[] roomEvents = room.getRoomEvents( 
    0, // no time restriction = since room creation
    new RoomStatusAction[] { RoomStatusAction.ROOM_ADD_USER,
                             RoomStatusAction.ROOM_REMOVE_USER,
                             RoomStatusAction.ROOM_CHANGE_USER_ROLE },
    null, // all users
    50 // at most 50 events
  );

  for ( int i = 0; i < roomEvents.length; i++ )
  {
    // process events
    // ...
    // for instance: print message
    System.out.println( roomEvents[i].getMessage() );
  }
}

How to Use the Rooms API

How to... retrieve all rooms to which a user belongs